<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<!--[if lt IE 9]>
  <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<![endif]-->
<title>VIM 中文帮助: 关于如何使用帮助文件</title>
<link rel="stylesheet" href="vim-stylesheet.css" type="text/css" />
<link rel="canonical" href="https://yianwillis.github.io/vimcdoc/doc/helphelp.html" />
<script type="text/javascript" src="vimcdoc.js"></script>
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<nav id=banner>
<form action=tags.html target="tag_iframe">
  <input type="text" name="tag" id="tag" placeholder="标签搜索">
</form>
<iframe name="tag_iframe" src=""></iframe>
<a href="help.html">帮助总览</a> &middot;
<hr/>
<a href="quickref.html">快速参考</a> &middot;
<a href="index.html">命令索引</a> &middot;
<a href="eval.html#functions">函数列表</a> &middot;
<a href="quickref.html#option-list">选项列表</a> &middot;
<hr/>
<a href="usr_toc.html">用户手册</a> &middot;
<a href="help.html#reference_toc">参考手册</a> &middot;
</nav>

<header>
<h2>helphelp</h2>
</header>
<article id=outer>
<section class=inner>
<b class="vimtag"> <a name="helphelp.txt">helphelp.txt</a> </b>  适用于 Vim 9.0 版本。   最近更新: 2022年7月


                  <code class="vim">VIM 参考手册    by Bram Moolenaar</code>
                                <code class="vim">译者</code>: Willis


帮助文件之帮助                                          <b class="vimtag"> <a name="helphelp">helphelp</a> </b>

1. 帮助命令                      <a href="helphelp.html#online-help">online-help</a> 
2. 翻译帮助文件                  <a href="helphelp.html#help-translated">help-translated</a> 
3. 编写帮助文件                  <a href="helphelp.html#help-writing">help-writing</a> 

</section><hr class="doubleline" /><section class=inner>
<h4>1. 帮助命令                                             <b class="vimtag"> <a name="online-help">online-help</a> </b></h4>
                        <b class="vimtag"> <a name="help">help</a> </b> <b class="vimtag"> <a name="%3CHelp%3E">&lt;Help&gt;</a> </b> <b class="vimtag"> <a name=":h">:h</a> </b> <b class="vimtag"> <a name=":help">:help</a> </b> <b class="vimtag"> <a name="%3CF1%3E">&lt;F1&gt;</a> </b> <b class="vimtag"> <a name="i_%3CF1%3E">i_&lt;F1&gt;</a> </b> <b class="vimtag"> <a name="i_%3CHelp%3E">i_&lt;Help&gt;</a> </b>
<code class="special">&lt;Help&gt;</code>          或
:h[elp]                 打开一个窗口并以只读方式显示帮助文件。如果已经打开了一
                        个帮助窗口，就继续使用那个窗口。不然，如果当前窗口占据
                        了屏幕的完整宽度或者至少有 80 个字符宽，帮助窗口会出现
                        在当前窗口的正上方。再不然，新窗口就开在最上方。
                        如果主帮助文件有多个语言版本，<a href="options.html#'helplang'">'helplang'</a> 选项选择使用
                        的语言。

                                                <b class="vimtag"> <a name="{subject}">{subject}</a> </b> <b class="vimtag"> <a name="E149">E149</a> </b> <b class="vimtag"> <a name="E661">E661</a> </b>
:h[elp] <code class="special">{subject}</code>       类似于 ":help"，但附加跳转到 <code class="special">{subject}</code> 标签上。
                        例如: 
<code class="example">                                :help options</code>
<code class="example"></code>
                        <code class="special">{subject}</code> 可以包含 "*"、"?" 和 "[a-z]" 这样的通配符:
                           :help z?     跳到任何包含 "z" 的命令的帮助
                           :help z.     跳到关于 "z." 的帮助
                        但如果标签存在，按本义接受:
                           :help :?     跳到关于 ":?" 的帮助

                        如果不能完全匹配该模式，或者有多个匹配，那就使用 "最
                        好" 的匹配。这里，有一个相当复杂的算法来排定匹配的优先
                        顺序。它的计算涉及到以下诸方面:
                        - 大小写完全相同的优先于大小写不完全相同的。
                        - 开始于非字母数字之后的优先于从单词中间开始的。
                        - 位于或接近标签开始处的优先于离此距离较远的。
                        - 匹配的字母数字字符越多越优先。
                        - 匹配越短的越优先。

                        如果该 <code class="special">{subject}</code> 有多个语言的帮助，<a href="options.html#'helplang'">'helplang'</a> 选项用来
                        选择所用的语言。要找到某个标签某个特定的语言版本，附加
                        上 "@ab"，其中 "ab" 是双字母的语言代码。参见
                         <a href="helphelp.html#help-translated">help-translated</a> 。

                        <code class="note">注意</code> 给出越长的 <code class="special">{subect}</code>，找到的匹配就越少。通过使用命
                        令行补全功能 (在 ":help subject" 之后输入 <code class="keystroke">CTRL-D</code>
                         <a href="cmdline.html#c_CTRL-D">c_CTRL-D</a> ) 可以帮助你了解这是如何工作的。
                        如果有多个匹配，你可以通过敲击 <code class="keystroke">CTRL-D</code> 得到匹配的列表。
                        例如: 
<code class="example">                                :help cont&lt;Ctrl-D&gt;</code>
<code class="example"></code>
                        要找寻 <code class="keystroke">CTRL-V</code> 的帮助不需要打 ":help <code class="keystroke">CTRL-V</code>"，可用: 
<code class="example">                                :help ^V</code>
                        这也适用于和其它字符混用的情况。例如寻找 <code class="keystroke">CTRL-V</code> 在插入
                        模式的帮助: 
<code class="example">                                :help i^V</code>

                        也可以先 ":help"，然后在帮助窗口里 ":tag <code class="special">{pattern}</code>"。
                        此时可用 ":tnext" 命令跳转到后一个匹配，"tselect" 列出
                        所有的匹配并让你选择一个。 
<code class="example">                                :help index</code>
<code class="example">                                :tselect /.*mode</code>
<code class="example"></code>
                        如果没有参数，你会看到 "help" 的匹配而不是列出所有可能
                        的匹配 (那会非常慢)。
                        显示的匹配个数限于 300 个。

                         <a href="helphelp.html#:help">:help</a>  命令可以后跟 '|' 并紧跟另外一个命令。不过，你
                        不需要在 help 命令里转义 '|'。所以下面这些都没问题: 
<code class="example">                                :help |</code>
<code class="example">                                :help k| only</code>
                        <code class="note">注意</code> '|' 之前的空格视为 ":help" 参数的一部分。
                        (<code class="vim">译者注</code>: 前者查找 | 的帮助，后者查找 k 的帮助并执行
                        only 命令使帮助窗口成为唯一窗口)
                        也可用 <code class="special">&lt;NL&gt;</code> 或 <code class="special">&lt;CR&gt;</code> 来分隔 help 命令和其后的命令。你需
                        要先输入 <code class="keystroke">CTRL-V</code>，再输入 <code class="special">&lt;NL&gt;</code> 或 <code class="special">&lt;CR&gt;</code>。例如: 
<code class="example">                                :help so&lt;C-V&gt;&lt;CR&gt;only</code>
<code class="example"></code>
:h[elp]! <code class="special">[subject]</code>      类似于 ":help"，但在非英语帮助文件里，优先查找和当前文
                        件相同语言的文件中的标签。参见  <a href="helphelp.html#help-translated">help-translated</a> 。

                                                        <b class="vimtag"> <a name=":helpc">:helpc</a> </b> <b class="vimtag"> <a name=":helpclose">:helpclose</a> </b>
:helpc[lose]            如果有的话，关闭一个帮助窗口。
                        Vim 会试图恢复打开帮助窗口之前原先的窗口布局 (包括光标
                        位置)。这可能会触发若干自动命令。

                                                        <b class="vimtag"> <a name=":helpg">:helpg</a> </b> <b class="vimtag"> <a name=":helpgrep">:helpgrep</a> </b>
:helpg[rep] <code class="special">{pattern}</code>[@xx]
                        搜索所有的帮助文本并给出匹配 <code class="special">{pattern}</code> 行的列表。跳转
                        到第一个匹配。
                        可选的 [@xx] 指定只寻找 "xx" 语言里的匹配。
                        你可以用  <a href="quickfix.html#quickfix">quickfix</a>  命令来浏览其它的匹配。例如，
                         <a href="quickfix.html#:cnext">:cnext</a>  会跳到下一个匹配。从快速修复窗口里也可用
                         <a href="quickfix.html#:cwindow">:cwindow</a>  得到所有匹配的列表。
                        <code class="special">{pattern}</code> 为 Vim 正则表达式  <a href="pattern.html#pattern">pattern</a> 。
                        不使用 <a href="options.html#'ignorecase'">'ignorecase'</a>，你可以加上 "\c" 来忽略大小写。
                        大小写敏感的搜索示例: 
<code class="example">                                :helpgrep Uganda</code>
                        大小写不敏感的搜索示例: 
<code class="example">                                :helpgrep uganda\c</code>
                        寻找中文帮助的搜索: 
<code class="example">                                :helpgrep backspace@cn</code>
                        模式不支持换行符，必须在一行内匹配。否则可用  <a href="quickfix.html#:grep">:grep</a> 
                        代替，但要得到帮助文件的列表就比较复杂了。
                        后面不能跟其他的命令。其余部分都被当作模式的一部分。如
                        果需要，可以用  <a href="eval.html#:execute">:execute</a> 。
                        不会在压缩的帮助文件里搜索 (Fedora 会压缩帮助文件)。

                                                        <b class="vimtag"> <a name=":lh">:lh</a> </b> <b class="vimtag"> <a name=":lhelpgrep">:lhelpgrep</a> </b>
:lh[elpgrep] <code class="special">{pattern}</code>[@xx]
                        类似于 ":helpgrep"，但使用位置列表代替快速修复列表。如
                        果帮助窗口已经打开，使用该窗口的位置列表。不然，打开新
                        帮助窗口，并设置该窗口的位置列表。此时不改变当前窗口的
                        位置列表。

                                                        <b class="vimtag"> <a name=":exu">:exu</a> </b> <b class="vimtag"> <a name=":exusage">:exusage</a> </b>
:exu[sage]              显示 Ex 命令的帮助。目的是为了模拟对应的 Nvi 命令。

                                                        <b class="vimtag"> <a name=":viu">:viu</a> </b> <b class="vimtag"> <a name=":viusage">:viusage</a> </b>
:viu[sage]              显示普通命令的帮助。目的是为了模拟对应的 Nvi 命令。

没有给出参数时， <a href="helphelp.html#:help">:help</a>  会打开 <a href="options.html#'helpfile'">'helpfile'</a> 选项指定的文件。否则，在所有
<a href="options.html#'runtimepath'">'runtimepath'</a> 选项指定目录中的 "doc/tags" 文件里查找所要求的标签。

要在当前窗口打开帮助，见以下技巧:  <a href="tips.html#help-curwin">help-curwin</a> 。

可用 <a href="options.html#'helpheight'">'helpheight'</a> 选项来设置帮助窗口的起始高度 (缺省是 20)。

                                                <b class="vimtag"> <a name="help-buffer-options">help-buffer-options</a> </b>
创建帮助缓冲区时，设置若干局部选项以确保帮助文本以期待的方式显示:
    <a href="options.html#'iskeyword'">'iskeyword'</a>         几乎所有 ASCII 字符，除了 ' '、'*'、'"' 和 '|'
    <a href="options.html#'foldmethod'">'foldmethod'</a>        "manual"
    <a href="options.html#'tabstop'">'tabstop'</a>           8
    <a href="options.html#'arabic'">'arabic'</a>            关闭
    <a href="options.html#'binary'">'binary'</a>            关闭
    <a href="options.html#'buflisted'">'buflisted'</a>         关闭
    <a href="options.html#'cursorbind'">'cursorbind'</a>        关闭
    <a href="options.html#'diff'">'diff'</a>              关闭
    <a href="options.html#'foldenable'">'foldenable'</a>        关闭
    <a href="options.html#'list'">'list'</a>              关闭
    <a href="options.html#'modifiable'">'modifiable'</a>        关闭
    <a href="options.html#'number'">'number'</a>            关闭
    <a href="options.html#'relativenumber'">'relativenumber'</a>    关闭
    <a href="options.html#'rightleft'">'rightleft'</a>         关闭
    <a href="options.html#'scrollbind'">'scrollbind'</a>        关闭
    <a href="options.html#'spell'">'spell'</a>             关闭

标签用来跳转到指定的主题。有两种方法:
- 在命令或选项之上用 "<code class="keystroke">CTRL-]</code>" 命令。只有标签是关键字 (见 <a href="options.html#'iskeyword'">'iskeyword'</a>) 时才行。
  "<code class="special">&lt;C-Leftmouse&gt;</code>" 和 "g<code class="special">&lt;LeftMouse&gt;</code>" 等价于 "<code class="keystroke">CTRL-]</code>"。
- 用 ":ta <code class="special">{subject}</code>" 命令。也适用于包含非关键字字符的标签。

用 <code class="keystroke">CTRL-T</code> 或者 <code class="keystroke">CTRL-O</code> 跳回来。
用 ":q" 关闭帮助窗口。

如果查找的项目有多个可能匹配，可以这样依次跳转到每个匹配:
1. 先打开帮助窗口。
2. 用 ":tag" 命令，在标签前加上斜杠。例如: 
<code class="example">        :tag /min</code>
3. 用 ":tnext" 跳转到下一个匹配的标签。

可以为插件或其他项目增加帮助文件。为此不需要修改发布的帮助文件。见
 <a href="usr_05.html#add-local-help">add-local-help</a> 。

关于如何写本地的帮助文件，见  <a href="usr_51.html#write-local-help">write-local-help</a> 。

<code class="note">注意</code>: 本地帮助文件的标题行会自动列在帮助文件 "help.txt" 的 "LOCAL ADDITIONS"
一节  <code class="badlink">local-additions</code> 。只有在 Vim 里实际察看该文件才会这么做，该文件本身并没
有被修改。这是通过动态地遍历所有帮助文件并提取每个文件的首行来完成的。其中，跳
过 $VIMRUNTINE/doc 里的文件。
(<code class="vim">译者注</code>: 目前，即使使用经过翻译的帮助，本地帮助文件只能在英文的 help.txt 里看
到。用 :help@en 访问。)

                                                        <b class="vimtag"> <a name="help-xterm-window">help-xterm-window</a> </b>
如果你想在另外一个 xterm 窗口里察看帮助，可以用如下的命令: 
<code class="example">        :!xterm -e vim +help &amp;</code>


                        <b class="vimtag"> <a name=":helpfind">:helpfind</a> </b> <b class="vimtag"> <a name=":helpf">:helpf</a> </b>
:helpf[ind]             和  <a href="helphelp.html#:help">:help</a>  类似，但用一个对话框来提示输入参数。
                        这只是为了向后兼容的需要。它现在执行 ToolBar.FindHelp
                        菜单项而不是内建的对话框。
                        <code class="notvi">{仅当编译时加入  <a href="various.html#+GUI_GTK">+GUI_GTK</a>  特性才有效}</code>

                                        <b class="vimtag"> <a name=":helpt">:helpt</a> </b> <b class="vimtag"> <a name=":helptags">:helptags</a> </b>
                                <b class="vimtag"> <a name="E150">E150</a> </b> <b class="vimtag"> <a name="E151">E151</a> </b> <b class="vimtag"> <a name="E152">E152</a> </b> <b class="vimtag"> <a name="E153">E153</a> </b> <b class="vimtag"> <a name="E154">E154</a> </b> <b class="vimtag"> <a name="E670">E670</a> </b>
:helpt[ags] [++t] <code class="special">{dir}</code>
                        为目录 <code class="special">{dir}</code> 生成帮助标签文件 tags。<code class="special">{dir}</code> 为 ALL 时，
                        使用 <a href="options.html#'runtimepath'">'runtimepath'</a> 的所有 "doc" 目录。

                        扫描该目录及其子目录中所有的 "*.txt" 和 "*.??x" 文件中
                        帮助标签定义。标签定义出现在星号之间。"*.??x" 文件是经
                        过翻译的文件。它们相应产生 "tags-??" 文件，参见
                         <a href="helphelp.html#help-translated">help-translated</a> 。所生成的标签文件经过排序。
                        如果其中有重复项，会给出错误信息。
                        直接覆盖已有的标签文件，不会有提示。

                        可选的 "++t" 参数强制加入 "help-tags" 标签。如果 <code class="special">{dir}</code>
                        等于 $VIMRUNTIME/doc，也会这样做。

                        例如，要重建运行时目录的帮助标签 (需要有相应写权限): 
<code class="example">                                :helptags $VIMRUNTIME/doc</code>
<code class="example"></code>
</section><hr class="doubleline" /><section class=inner>
<h4>2. 翻 译 帮 助 文 件                                    <b class="vimtag"> <a name="help-translated">help-translated</a> </b></h4>
除了原始的英语帮助文件外，我们可以添加其他语言的翻译版本。Vim 会在所有
<a href="options.html#'runtimepath'">'runtimepath'</a> 的目录的 "doc" 子目录里查找帮助文件。这只有在编译时加入
 <a href="various.html#+multi_lang">+multi_lang</a>  特性才会有效。

目前，有以下的翻译可用:
        中文     - 多位作者
        法语     - David Blanchet 翻译
        意大利语 - Antonio Colombo 翻译
        日文     - 多位作者
        波兰语   - Mikolaj Machowski 翻译
        俄罗斯语 - Vassily Ragosin 翻译
在 Vim 网页上可以找到这些翻译: <a href="http://www.vim.org/translations.php">http://www.vim.org/translations.php</a>

帮助文件的翻译版本包含如下文件:

        help.abx
        howto.abx
        ...
        tags-ab

"ab" 是一个双字母的语言代码。这样，中文的文件名是:

        help.cnx
        howto.cnx
        ...
        tags-cn

<a href="options.html#'helplang'">'helplang'</a> 选项设置若干语言偏好。 缺省值根据当前环境设置。Vim 会先在偏好的语言
里查找匹配的标签。如果没有，就使用英语版本。

要查找某一特定的语言的标签，在标签后面加上 "@ab"，其中的 "ab" 是两字节的语言代
码。示例: 
<code class="example">        :he user-manual@cn</code>
<code class="example">        :he user-manual@en</code>
前者查找中文的用户手册，即使 <a href="options.html#'helplang'">'helplang'</a> 为空。后者查找英语用户手册，即使
<a href="options.html#'helplang'">'helplang'</a> 设置为 "cn"。

":help" 的命令行补全只会在有多个语言版本的标签时显示 "@en" 后缀。如果只有英语
版本，"@en" 就省略。如果首个候选有 "@ab" 后缀而该后缀匹配 <a href="options.html#'helplang'">'helplang'</a> 的首选语
言，则 "@ab" 也被省略。

如果在一个非英语帮助文件里使用  <a href="tagsrch.html#CTRL-]">CTRL-]</a>  或者 ":help!"，Vim 会先找相同语言的标
签。如果没有，再根据 <a href="options.html#'helplang'">'helplang'</a> 选择语言。

Help 文件一定要使用 latin1 或 utf-8 编码。Vim 如果发现首行有非 ASCII 的字符，
就假设是 utf-8 编码。所以，你至少要翻译头部的 "For Vim version"。

同一个目录里相同语言的帮助文件必须使用相同的编码。不同语言或者相同语言但在不同
的目录下可以使用不同的编码。

为<code class="vim">译者</code>的提示:
- 不要翻译标签本身。这样才能用 <a href="options.html#'helplang'">'helplang'</a> 来指定语言偏好。你可以在自己的语言里
  加入新的标签。
- 如果不想翻译文件的部分内容，用 "tag@en" 的形式标记英语版本的标签。
- 生成一个包，包含所有的帮助和和标签文件，以便下载。用户把它解开到某个 "doc"
  目录下就可以开始使用了。请告知 Bram，他可以在 www.vim.org 上给加一个链接。
- 用  <a href="helphelp.html#:helptags">:helptags</a>  命令生成标签文件 tags。该命令会在指定目录下找到所有语言的版
  本。

</section><hr class="doubleline" /><section class=inner>
<h4>3. 编 写 帮 助 文 件                                    <b class="vimtag"> <a name="help-writing">help-writing</a> </b></h4>
为了方便使用，为插件编写的 Vim 帮助文件应该遵循标准 Vim 帮助文件的格式，首行除
外。如果你在编写新帮助文件，最好从现有的文件复制一份作为模板。

帮助文件的首行的格式应该是这样的:

<b class="vimtag"> <a name="plugin_name.txt">plugin_name.txt</a> </b>       <code class="special">{插件的简单描述}</code>

第一个字段是 ":help plugin_name" 会跳转到的帮助标签。在制表符之后的此行其余部
分简短描述插件的目的。它会显示在主帮助文件的 "LOCAL ADDITIONS" 小节下。现在要
检查一下，可跳转到:  <code class="badlink">local-additions</code> 。

如果需要版本号或最后修改日期，放在第二行并右对齐。

在帮助文件的底部放上 Vim 的模式行，它设置 <a href="options.html#'textwidth'">'textwidth'</a>、<a href="options.html#'tabstop'">'tabstop'</a> 选项，并把
<a href="options.html#'filetype'">'filetype'</a> 设为 "help"。请不要在模式行上设置全局选项，否则会有不希望的后果。


标 签

要定义帮助标签，把名字放在星号之间 (*标签名*)。标签名应该和所有 Vim 帮助标签名
不同，最好以 Vim 插件名开头。标签名通常行右对齐。

要引用已有帮助标签并建立一个热链，把名字放在竖线 (|) 之间，如  <a href="helphelp.html#help-writing">help-writing</a> 。

要引用 Vim 命令并建立一个热链，把名字放在反引号之间，例如  <a href="filetype.html#:filetype">:filetype</a>  里。可见
它以命令形式高亮，如同代码块那样 (见下)。

要在帮助文件里引用 Vim 选项，可以把选项名在单引号之间，如 <a href="options.html#'statusline'">'statusline'</a>。


高 亮

要定义栏标题，在行尾加上波浪符。栏标题会使用不同颜色的高亮。例如

<code class="section">栏标题</code>

要分隔同一帮助文件的不同小节，加上一行从首列开始的 '=' 字符序列。小节分隔行会
使用不同的高亮。

要不加修饰地引用一段 ex 命令块，在块之前的那行最后加上一个大于号 (&gt;) 字符，然
后在块之后的那行放上一个小于号 (&lt;) 字符作为该行的第一个非空白字符。任何从第一
列开始的行也会隐含地结束之前的 ex 命令块。例如 
<code class="example">    function Example_Func()</code>
<code class="example">        echo "Example"</code>
<code class="example">    endfunction</code>


以下内容在 Vim 帮助文件中采用不同的高亮:
  - 使用 <code class="special">&lt;&gt;</code> 记号的特殊键名，如 <code class="special">&lt;PageDown&gt;</code>，或 Ctrl 字符，如 <code class="keystroke">CTRL-X</code>
  - 任何 <code class="special">{花括号}</code> 之间的内容，如 <code class="special">{lhs}</code> 和 <code class="special">{rhs}</code>

"Note"，"Notes" 和类似的单词会神奇地自动得到独特的高亮，下面的也是:
        *Todo   something to do
        *Error  something wrong

具体细节可见 $VIMRUNTIME/syntax/help.vim

                                                        <b class="vimtag"> <a name="inclusion">inclusion</a> </b>
Vim 目标是服务所有人，不论种族、性别或其它。有些人很在意用户指称使用了 "他" 或
"他的"，认为我们假定用户是男性。事实不是如此，这只是写帮助文本时的一种习惯，且
已沿习多年。另外，大量文本由英语不是第一语言的贡献者编写。不管行文如何，我们都
没有关于用户性别的任何假定。有些人建议使用 "他们" (<code class="vim">译者注</code>: 英语该词是中性的)，
但这不是常规英语。我们也不想花时间在这方面的讨论上。我们的目标是帮助读者理解
Vim 如何工作，准确的措词是第二位的。


 vim:tw=78:ts=8:noet:ft=help:norl:
</section>
</article>
<footer>
Generated by vim2html
</footer>
</body>
</html>
